home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / dns / dispatch.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  11.4 KB  |  451 lines
  1. /*
  2.  * Copyright (C) 2004, 2005, 2007, 2008  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 1999-2003  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and/or distribute this software for any
  6.  * purpose with or without fee is hereby granted, provided that the above
  7.  * copyright notice and this permission notice appear in all copies.
  8.  *
  9.  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10.  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11.  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12.  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13.  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14.  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15.  * PERFORMANCE OF THIS SOFTWARE.
  16.  */
  17.  
  18. /* $Id: dispatch.h,v 1.48.18.5.12.2 2008/07/23 07:28:56 tbox Exp $ */
  19.  
  20. #ifndef DNS_DISPATCH_H
  21. #define DNS_DISPATCH_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  28.  * \brief
  29.  * DNS Dispatch Management
  30.  *     Shared UDP and single-use TCP dispatches for queries and responses.
  31.  *
  32.  * MP:
  33.  *
  34.  *\li         All locking is performed internally to each dispatch.
  35.  *     Restrictions apply to dns_dispatch_removeresponse().
  36.  *
  37.  * Reliability:
  38.  *
  39.  * Resources:
  40.  *
  41.  * Security:
  42.  *
  43.  *\li    Depends on the isc_socket_t and dns_message_t for prevention of
  44.  *    buffer overruns.
  45.  *
  46.  * Standards:
  47.  *
  48.  *\li    None.
  49.  */
  50.  
  51. /***
  52.  *** Imports
  53.  ***/
  54.  
  55. #include <isc/buffer.h>
  56. #include <isc/lang.h>
  57. #include <isc/socket.h>
  58. #include <dns/types.h>
  59.  
  60. #include <dns/types.h>
  61.  
  62. ISC_LANG_BEGINDECLS
  63.  
  64. /*%
  65.  * This event is sent to a task when a response comes in.
  66.  * No part of this structure should ever be modified by the caller,
  67.  * other than parts of the buffer.  The holy parts of the buffer are
  68.  * the base and size of the buffer.  All other parts of the buffer may
  69.  * be used.  On event delivery the used region contains the packet.
  70.  *
  71.  * "id" is the received message id,
  72.  *
  73.  * "addr" is the host that sent it to us,
  74.  *
  75.  * "buffer" holds state on the received data.
  76.  *
  77.  * The "free" routine for this event will clean up itself as well as
  78.  * any buffer space allocated from common pools.
  79.  */
  80.  
  81. struct dns_dispatchevent {
  82.     ISC_EVENT_COMMON(dns_dispatchevent_t);    /*%< standard event common */
  83.     isc_result_t        result;        /*%< result code */
  84.     isc_int32_t        id;        /*%< message id */
  85.     isc_sockaddr_t        addr;        /*%< address recv'd from */
  86.     struct in6_pktinfo    pktinfo;    /*%< reply info for v6 */
  87.     isc_buffer_t            buffer;        /*%< data buffer */
  88.     isc_uint32_t        attributes;    /*%< mirrored from socket.h */
  89. };
  90.  
  91. /*@{*/
  92. /*%
  93.  * Attributes for added dispatchers.
  94.  *
  95.  * Values with the mask 0xffff0000 are application defined.
  96.  * Values with the mask 0x0000ffff are library defined.
  97.  *
  98.  * Insane values (like setting both TCP and UDP) are not caught.  Don't
  99.  * do that.
  100.  *
  101.  * _PRIVATE
  102.  *    The dispatcher cannot be shared.
  103.  *
  104.  * _TCP, _UDP
  105.  *    The dispatcher is a TCP or UDP socket.
  106.  *
  107.  * _IPV4, _IPV6
  108.  *    The dispatcher uses an ipv4 or ipv6 socket.
  109.  *
  110.  * _NOLISTEN
  111.  *    The dispatcher should not listen on the socket.
  112.  *
  113.  * _MAKEQUERY
  114.  *    The dispatcher can be used to issue queries to other servers, and
  115.  *    accept replies from them.
  116.  *
  117.  * _RANDOMPORT
  118.  *    Allocate UDP port randomly.
  119.  */
  120. #define DNS_DISPATCHATTR_PRIVATE    0x00000001U
  121. #define DNS_DISPATCHATTR_TCP        0x00000002U
  122. #define DNS_DISPATCHATTR_UDP        0x00000004U
  123. #define DNS_DISPATCHATTR_IPV4        0x00000008U
  124. #define DNS_DISPATCHATTR_IPV6        0x00000010U
  125. #define DNS_DISPATCHATTR_NOLISTEN    0x00000020U
  126. #define DNS_DISPATCHATTR_MAKEQUERY    0x00000040U
  127. #define DNS_DISPATCHATTR_CONNECTED    0x00000080U
  128. #define DNS_DISPATCHATTR_RANDOMPORT    0x00000100U
  129. /*@}*/
  130.  
  131. isc_result_t
  132. dns_dispatchmgr_create(isc_mem_t *mctx, isc_entropy_t *entropy,
  133.                dns_dispatchmgr_t **mgrp);
  134. /*%<
  135.  * Creates a new dispatchmgr object.
  136.  *
  137.  * Requires:
  138.  *\li    "mctx" be a valid memory context.
  139.  *
  140.  *\li    mgrp != NULL && *mgrp == NULL
  141.  *
  142.  *\li    "entropy" may be NULL, in which case an insecure random generator
  143.  *    will be used.  If it is non-NULL, it must be a valid entropy
  144.  *    source.
  145.  *
  146.  * Returns:
  147.  *\li    ISC_R_SUCCESS    -- all ok
  148.  *
  149.  *\li    anything else    -- failure
  150.  */
  151.  
  152.  
  153. void
  154. dns_dispatchmgr_destroy(dns_dispatchmgr_t **mgrp);
  155. /*%<
  156.  * Destroys the dispatchmgr when it becomes empty.  This could be
  157.  * immediately.
  158.  *
  159.  * Requires:
  160.  *\li    mgrp != NULL && *mgrp is a valid dispatchmgr.
  161.  */
  162.  
  163.  
  164. void
  165. dns_dispatchmgr_setblackhole(dns_dispatchmgr_t *mgr, dns_acl_t *blackhole);
  166. /*%<
  167.  * Sets the dispatcher's "blackhole list," a list of addresses that will
  168.  * be ignored by all dispatchers created by the dispatchmgr.
  169.  *
  170.  * Requires:
  171.  * \li    mgrp is a valid dispatchmgr
  172.  * \li    blackhole is a valid acl
  173.  */
  174.  
  175.  
  176. dns_acl_t *
  177. dns_dispatchmgr_getblackhole(dns_dispatchmgr_t *mgr);
  178. /*%<
  179.  * Gets a pointer to the dispatcher's current blackhole list,
  180.  * without incrementing its reference count.
  181.  *
  182.  * Requires:
  183.  *\li     mgr is a valid dispatchmgr
  184.  * Returns:
  185.  *\li    A pointer to the current blackhole list, or NULL.
  186.  */
  187.  
  188. void
  189. dns_dispatchmgr_setblackportlist(dns_dispatchmgr_t *mgr,
  190.                                  dns_portlist_t *portlist);
  191. /*%<
  192.  * Sets a list of UDP ports that won't be used when creating a udp
  193.  * dispatch with a wildcard port.
  194.  *
  195.  * Requires:
  196.  *\li    mgr is a valid dispatchmgr
  197.  *\li    portlist to be NULL or a valid port list.
  198.  */
  199.  
  200. dns_portlist_t *
  201. dns_dispatchmgr_getblackportlist(dns_dispatchmgr_t *mgr);
  202. /*%<
  203.  * Return the current port list.
  204.  *
  205.  * Requires:
  206.  *\li    mgr is a valid dispatchmgr
  207.  */
  208.  
  209.  
  210.  
  211. isc_result_t
  212. dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
  213.             isc_taskmgr_t *taskmgr, isc_sockaddr_t *localaddr,
  214.             unsigned int buffersize,
  215.             unsigned int maxbuffers, unsigned int maxrequests,
  216.             unsigned int buckets, unsigned int increment,
  217.             unsigned int attributes, unsigned int mask,
  218.             dns_dispatch_t **dispp);
  219. /*%<
  220.  * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find,
  221.  * otherwise create a new UDP dispatch.
  222.  *
  223.  * Requires:
  224.  *\li    All pointer parameters be valid for their respective types.
  225.  *
  226.  *\li    dispp != NULL && *disp == NULL
  227.  *
  228.  *\li    512 <= buffersize <= 64k
  229.  *
  230.  *\li    maxbuffers > 0
  231.  *
  232.  *\li    buckets < 2097169
  233.  *
  234.  *\li    increment > buckets
  235.  *
  236.  *\li    (attributes & DNS_DISPATCHATTR_TCP) == 0
  237.  *
  238.  * Returns:
  239.  *\li    ISC_R_SUCCESS    -- success.
  240.  *
  241.  *\li    Anything else    -- failure.
  242.  */
  243.  
  244. isc_result_t
  245. dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
  246.                isc_taskmgr_t *taskmgr, unsigned int buffersize,
  247.                unsigned int maxbuffers, unsigned int maxrequests,
  248.                unsigned int buckets, unsigned int increment,
  249.                unsigned int attributes, dns_dispatch_t **dispp);
  250. /*%<
  251.  * Create a new dns_dispatch and attach it to the provided isc_socket_t.
  252.  *
  253.  * For all dispatches, "buffersize" is the maximum packet size we will
  254.  * accept.
  255.  *
  256.  * "maxbuffers" and "maxrequests" control the number of buffers in the
  257.  * overall system and the number of buffers which can be allocated to
  258.  * requests.
  259.  *
  260.  * "buckets" is the number of buckets to use, and should be prime.
  261.  *
  262.  * "increment" is used in a collision avoidance function, and needs to be
  263.  * a prime > buckets, and not 2.
  264.  *
  265.  * Requires:
  266.  *
  267.  *\li    mgr is a valid dispatch manager.
  268.  *
  269.  *\li    sock is a valid.
  270.  *
  271.  *\li    task is a valid task that can be used internally to this dispatcher.
  272.  *
  273.  * \li    512 <= buffersize <= 64k
  274.  *
  275.  *\li    maxbuffers > 0.
  276.  *
  277.  *\li    maxrequests <= maxbuffers.
  278.  *
  279.  *\li    buckets < 2097169 (the next prime after 65536 * 32)
  280.  *
  281.  *\li    increment > buckets (and prime).
  282.  *
  283.  *\li    attributes includes #DNS_DISPATCHATTR_TCP and does not include
  284.  *    #DNS_DISPATCHATTR_UDP.
  285.  *
  286.  * Returns:
  287.  *\li    ISC_R_SUCCESS    -- success.
  288.  *
  289.  *\li    Anything else    -- failure.
  290.  */
  291.  
  292. void
  293. dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp);
  294. /*%<
  295.  * Attach to a dispatch handle.
  296.  *
  297.  * Requires:
  298.  *\li    disp is valid.
  299.  *
  300.  *\li    dispp != NULL && *dispp == NULL
  301.  */
  302.  
  303. void
  304. dns_dispatch_detach(dns_dispatch_t **dispp);
  305. /*%<
  306.  * Detaches from the dispatch.
  307.  *
  308.  * Requires:
  309.  *\li    dispp != NULL and *dispp be a valid dispatch.
  310.  */
  311.  
  312. void
  313. dns_dispatch_starttcp(dns_dispatch_t *disp);
  314. /*%<
  315.  * Start processing of a TCP dispatch once the socket connects.
  316.  *
  317.  * Requires:
  318.  *\li    'disp' is valid.
  319.  */
  320.  
  321. isc_result_t
  322. dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest,
  323.              isc_task_t *task, isc_taskaction_t action, void *arg,
  324.              isc_uint16_t *idp, dns_dispentry_t **resp);
  325. /*%<
  326.  * Add a response entry for this dispatch.
  327.  *
  328.  * "*idp" is filled in with the assigned message ID, and *resp is filled in
  329.  * to contain the magic token used to request event flow stop.
  330.  *
  331.  * Arranges for the given task to get a callback for response packets.  When
  332.  * the event is delivered, it must be returned using dns_dispatch_freeevent()
  333.  * or through dns_dispatch_removeresponse() for another to be delivered.
  334.  *
  335.  * Requires:
  336.  *\li    "idp" be non-NULL.
  337.  *
  338.  *\li    "task" "action" and "arg" be set as appropriate.
  339.  *
  340.  *\li    "dest" be non-NULL and valid.
  341.  *
  342.  *\li    "resp" be non-NULL and *resp be NULL
  343.  *
  344.  * Ensures:
  345.  *
  346.  *\li    <id, dest> is a unique tuple.  That means incoming messages
  347.  *    are identifiable.
  348.  *
  349.  * Returns:
  350.  *
  351.  *\li    ISC_R_SUCCESS        -- all is well.
  352.  *\li    ISC_R_NOMEMORY        -- memory could not be allocated.
  353.  *\li    ISC_R_NOMORE        -- no more message ids can be allocated
  354.  *                   for this destination.
  355.  */
  356.  
  357.  
  358. void
  359. dns_dispatch_removeresponse(dns_dispentry_t **resp,
  360.                 dns_dispatchevent_t **sockevent);
  361. /*%<
  362.  * Stops the flow of responses for the provided id and destination.
  363.  * If "sockevent" is non-NULL, the dispatch event and associated buffer is
  364.  * also returned to the system.
  365.  *
  366.  * Requires:
  367.  *\li    "resp" != NULL and "*resp" contain a value previously allocated
  368.  *    by dns_dispatch_addresponse();
  369.  *
  370.  *\li    May only be called from within the task given as the 'task' 
  371.  *     argument to dns_dispatch_addresponse() when allocating '*resp'.
  372.  */
  373.  
  374.  
  375. isc_socket_t *
  376. dns_dispatch_getsocket(dns_dispatch_t *disp);
  377. /*%<
  378.  * Return the socket associated with this dispatcher.
  379.  *
  380.  * Requires:
  381.  *\li    disp is valid.
  382.  *
  383.  * Returns:
  384.  *\li    The socket the dispatcher is using.
  385.  */
  386.  
  387. isc_result_t 
  388. dns_dispatch_getlocaladdress(dns_dispatch_t *disp, isc_sockaddr_t *addrp);
  389. /*%<
  390.  * Return the local address for this dispatch.
  391.  * This currently only works for dispatches using UDP sockets.
  392.  *
  393.  * Requires:
  394.  *\li    disp is valid.
  395.  *\li    addrp to be non null.
  396.  *
  397.  * Returns:
  398.  *\li    ISC_R_SUCCESS    
  399.  *\li    ISC_R_NOTIMPLEMENTED
  400.  */
  401.  
  402. void
  403. dns_dispatch_cancel(dns_dispatch_t *disp);
  404. /*%<
  405.  * cancel outstanding clients
  406.  *
  407.  * Requires:
  408.  *\li    disp is valid.
  409.  */
  410.  
  411. void
  412. dns_dispatch_changeattributes(dns_dispatch_t *disp,
  413.                   unsigned int attributes, unsigned int mask);
  414. /*%<
  415.  * Set the bits described by "mask" to the corresponding values in
  416.  * "attributes".
  417.  *
  418.  * That is:
  419.  *
  420.  * \code
  421.  *    new = (old & ~mask) | (attributes & mask)
  422.  * \endcode
  423.  *
  424.  * This function has a side effect when #DNS_DISPATCHATTR_NOLISTEN changes. 
  425.  * When the flag becomes off, the dispatch will start receiving on the
  426.  * corresponding socket.  When the flag becomes on, receive events on the
  427.  * corresponding socket will be canceled.
  428.  *
  429.  * Requires:
  430.  *\li    disp is valid.
  431.  *
  432.  *\li    attributes are reasonable for the dispatch.  That is, setting the UDP
  433.  *    attribute on a TCP socket isn't reasonable.
  434.  */
  435.  
  436. void
  437. dns_dispatch_importrecv(dns_dispatch_t *disp, isc_event_t *event);
  438. /*%<
  439.  * Inform the dispatcher of a socket receive.  This is used for sockets
  440.  * shared between dispatchers and clients.  If the dispatcher fails to copy
  441.  * or send the event, nothing happens.
  442.  *
  443.  * Requires:
  444.  *\li     disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set.
  445.  *     event != NULL
  446.  */
  447.  
  448. ISC_LANG_ENDDECLS
  449.  
  450. #endif /* DNS_DISPATCH_H */
  451.